Penny Drop - Bank Account Verification API

The following document highlights the details of the Penny Drop API.

API Description

Objective

The Penny Drop API validates a bank account number and the Indian Financial System Code(IFSC) associated with it by making a transaction of 1 rupee (a penny drop).

Input	Output
The account number and its IFSC	The response indicating the status of the transaction and additional details such as the account holder's name

API URL

https://ind-engine.thomas.hyperverge.co/v1/checkBankAccount

API Endpoint

checkBankAccount

Overview

The Penny Drop API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the Penny Drop API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
ifsc	Mandatory	string	The IFSC of the account's branch	Not Applicable	Not Applicable
accountNumber	Mandatory	string	The account number associated with the bank account	Not Applicable	Not Applicable
strictValidation	Optional	string	This parameter triggers a failure response for Blocked and Overseas accounts if the account name cannot be retrieved. Refer to the Error Responses section for a complete overview of the responses returned when this parameter is enabled in the request.	yes / no	no

Request

The following code snippet demonstrates a standard curl request for the Penny Drop API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/checkBankAccount' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "ifsc": "<IFSC code>",
    "accountNumber": "<Account number>",
    "strictValidation": "<Enter_Yes_or_No>"
}'

Success Response

The following code snippet demonstrates a success response from the Penny Drop API:

info

These are the responses returned when either the strictValidation parameter is not enabled in the request OR it is set to no.

Successful Penny-Drop

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "bankResponse": "Transaction Successful",
    "ifsc": "<IFSC>",
    "accountNumber": "<Account_Number>",
    "accountName": "<Name_of_the_Account_Holder>",
    "bankTxnStatus": true
  }
}

Non-Resident External (Overseas) Account

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "bankResponse": "NRE Account",
    "ifsc": "<IFSC>",
    "accountNumber": "<Account_Number>",
    "accountName": "<Name_of_the_Account_Holder>",
    "bankTxnStatus": true
  }
}

Success Response Details

The following table outlines the details of the success response from the Penny Drop API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	object	The JSON object containing the bank account verification details
result.bankResponse	string	Indicates the result of the transaction, signaling whether it was a success or a failure.
result.ifsc	string	The IFSC Code of the bank account for reference.
result.accountNumber	string	The account number associated with the bank transaction.
result.accountName	string	The name of the account holder associated with the bank account.
result.bankTxnStatus	boolean	Indicates the status of the transaction, with a value of "true" if the transaction was successful and "false" if it was not.

Failure Response

The following code snippet demonstrates a failure response from the Penny Drop API for a blocked account:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "bankResponse": "Account is blocked",
    "ifsc": "<Enter_the_IFSC>",
    "accountNumber": "<Enter_the_Account_Number>",
    "accountName": "<Enter_the_Name_of_the_Account_Holder>",
    "bankTxnStatus": false
  }
}

Error Responses

The following are some error responses from the Penny Drop API:

Invalid IFSC Length

{
  "status": "failure",
  "statusCode": "400",
  "error": "ifsc length must be 11 characters long"
}

Account Number Length is too Short

{
    "status": "failure",
    "statusCode": "400",
    "error": "accountNumber length must be at least 6 characters long"
}

Account Number Length is too Long

{
  "status": "failure",
  "statusCode": "400",
  "error": "accountNumber length must be less than or equal to 25 characters long"
}

Invalid Account Number or IFSC

{
  "status": "failure",
  "statusCode": "422",
  "error": "Invalid value passed for an input: Account number or IFSC"
}

Invalid Account Number

{
    "status": "failure",
    "statusCode": "422",
    "error": "Invalid value passed for an input: Account number"
}

Invalid IFSC

{
  "status": "failure",
  "statusCode": "422",
  "error": "Invalid value passed for an input: IFSC"
}

Invalid IFSC Pattern

{
  "status": "failure",
  "statusCode": "422",
  "error": "Invalid value passed for an input: IFSC pattern"
}

No accountName: Overseas Account

The following response is returned when the accountName cannot be retrieved for an Overseas account and when strictValidation is set to yes:

{
  "status": "failure",
  "statusCode": "422",
  "error": "Given account is an NRE account" // NRE, which stands for Non-Resident External, denotes the Overseas accounts
}

No accountName: Blocked Account

The following response is returned when the accountName cannot be retrieved for a Blocked account and when strictValidation is set to yes:

{
  "status": "failure",
  "statusCode": "422",
  "error": "Account is blocked"
}

Rate Limit Exceeded

{
  "status": "failure",
  "statusCode": "429",
  "error": "Requests rate limit exceeded"
}

Internal Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": "Internal Server Error"
}

Bank Error: IMPS Mode Fail

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: IMPS Mode Fail"
}

Bank Error: Beneficiary Bank Offline

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: Beneficiary Bank Offline"
}

Bank Error: Source Bank Declined

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: Source Bank Declined"
}

Bank Error: Failed at Bank

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: Failed at Bank"
}

Bank Error: Transaction Failed

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: Transaction Failed"
}

Bank Error: NPCI Unavailable

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: NPCI Unavailable"
}

Bank Error: Failed at Beneficiary Bank

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: Failed at Beneficiary Bank"
}

Bank Error: IMPS not supported on Beneficiary Account

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: IMPS not supported on Beneficiary Account"
}

Bank Error: Verification Attempt Failed

{
  "status": "failure",
  "statusCode": "500",
  "error": "Bank Error: Verification Attempt Failed"
}

Data Source Unavailable

{
  "status": "failure",
  "statusCode": "500",
  "error": "Data Source not Available"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	ifsc length must be 11 characters long	The length of the IFSC provided is not 11 characters long as required.	Provide an IFSC code that is exactly 11 characters long
400	accountNumber length must be at least 6 characters long	The length of the account number provided is less than the required minimum of 6 characters.	Provide an account number that is at least 6 characters long
400	accountNumber length must be less than or equal to 25 characters long	The length of the account number provided exceeds the maximum limit of 25 characters	Provide an account number that is 25 characters or less
422	Invalid value passed for an input: Account number or IFSC	An invalid value was provided for either the account number or IFSC in the input	Verify and provide valid account number and IFSC values
422	Invalid value passed for an input: Account number	An invalid value was provided for the account number in the input	Verify and provide a valid account number
422	Invalid value passed for an input: IFSC	An invalid value was provided for the IFSC in the input	Verify and provide a valid IFSC code
422	Invalid value passed for an input: IFSC pattern	An invalid value was provided for the IFSC pattern in the input	Provide an IFSC code that follows the correct format pattern
422	Given account is an NRE account	The accountName parameter — which provides the name of the user associated with the bank account — cannot be retrieved for an Overseas account. Only returned when the strictValidation parameter is enabled in the request and is set to yes	Use a non-NRE account or disable strictValidation if account name retrieval is not required
422	Account is blocked	The accountName parameter — which provides the name of the user associated with the bank account — cannot be retrieved for a Blocked account. Only returned when the strictValidation parameter is enabled in the request and is set to yes	Use an unblocked account or disable strictValidation if account name retrieval is not required
429	Requests rate limit exceeded	The rate limit for API requests has been exceeded.	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution
500	Bank Error: IMPS Mode Fail	A bank-related error, specifically the failure of the IMPS mode	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Bank Error: Beneficiary Bank Offline	A bank-related error, with the beneficiary bank being offline	Retry the request after some time when the bank is back online
500	Bank Error: Source Bank Declined	A bank-related error, with the source bank declining the transaction	Contact the source bank or retry the request after some time
500	Bank Error: Failed at Bank	A bank-related error, with the transaction failing at the bank	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Bank Error: Transaction Failed	A bank-related error, with the transaction failing	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Bank Error: NPCI Unavailable	A bank-related error, with the National Payments Corporation of India (NPCI) being unavailable	Retry the request after some time when NPCI services are available
500	Bank Error: Failed at Beneficiary Bank	A bank-related error, with the transaction failing at the beneficiary bank	Retry the request after some time or contact the beneficiary bank
500	Bank Error: IMPS not supported on Beneficiary Account	A bank-related error, with the beneficiary account not supporting IMPS	Use a different account that supports IMPS transactions
500	Bank Error: Verification Attempt Failed	A bank-related error, specifically a failure in the verification attempt	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Data Source not Available	The requested data source is temporarily unavailable	Retry the request after some time when the data source is available